feat(routes): CLI surface projections of MCP tools — colocated <tool>.cli.ts, mapInput, AB4843–AB4845 (#596) - #616

Closes #596. Builds on #593 (#603). Design comment (posted before implementation): #596 (comment).

What changes

One operation, two surface projections. The MCP tool module stays the only executable route (tool:<server>/<tool>: execution, inputSchema → RouteContract, resultSchema, domain errors, rendered document). Its MCP surface projection is the tool config as today. A new opt-in CLI surface projection is a colocated module that is never a route:

src/mcp/hauler/tools/hauler_request.tsx      # the operation
src/mcp/hauler/tools/hauler_request.cli.ts   # its CLI surface projection

import type { CliProjectionConfig } from 'agent-bundle/routes';
import type { inputSchema } from './hauler_request.js';

export const config = {
  command: ['request'],                       // default [tool]
  confirm: false,                             // default !(annotations.readOnlyHint === true)
  description: '…',
  flags: {
    after:   { description: '… (repeatable, or comma-separated)' },
    cwd:     { description: 'Workspace directory (default: current directory)', required: false },
    host:    { description: 'Agent host name for attribution' },
    session: { description: 'Agent session id for attribution' },
  },
  positionals: ['argv'],
} satisfies CliProjectionConfig<typeof inputSchema>;

export const mapInput = (input: CliInput): z.input<typeof inputSchema> => ({
  ...input, cwd: input.cwd ?? process.cwd(), ...(after.length === 0 ? {} : { after }),
});

Vocabulary follows #578/#592: host projection = targets (claude/codex/cursor/portable); surface projection = MCP tool vs CLI command (the code's existing surface axis: AgentInvocationKind, CompiledCliSurface). The two compose orthogonally; the routed CLI bin is still emitted once per composite root (AB4765/AB4766 unchanged).

Compiler (routes/cli-projection.ts new leaf; graph.ts, cli-commands.ts, cli-argv.ts). Discovery excludes src/mcp/*/tools/*.cli.{ts,tsx} from route classification before identity derivation (today such a file becomes the broken tool tool:<server>/<tool>.cli, AB4810) and pairs it with the sibling tool; _-prefixed parks it. config is read by the unchanged static grammar (extractRouteConfig: literals + string consts via the #593 resolver; satisfies unwraps); mapInput presence is recorded from scanRouteModuleExports().namedFunctions. compileProjectedCliCommands produces a CompiledCliCommand with routeId = the tool id, mcp: { server, tool, confirm } provenance, path = command ?? [tool], and options from the tool's RouteContract.input through the same cliOptionFor policy as src/cli routes with a per-key override (name, aliases, description, default, required: false) applied inside the policy so kebab/reserved/collision checks run on final spellings and aliases (yes reserved when confirming). A tool with a projection leaves the bulk routes.mcpCommands set (one command per operation; an include matching only such tools is AB4822 naming the module). AB4813 collisions cover projected commands with a projection recovery. A tool without a static contract but with a projection is judged like a CLI route: AB4814/AB4838/AB4839 fire with the prefix Tool route <path> (CLI projection <module>). AB4837 framework-import judgement applies to the projection module. safeIdentitySegment is now one shared export (two private copies removed).

Projection IR (routes/types.ts, additive; inspect --routes dumps it unchanged):

CompiledCliOption.aliases?: readonly string[]
CompiledCliProjection { mapInput: boolean; module: string /* project-relative */; defaults?: Record<key, scalar | scalar[]>; relaxed?: readonly string[] }
CompiledCliCommand.projection?: CompiledCliProjection
CompiledCliSurface.projectionSources?: Record<routeId, absolutePath>   // build-side, outside the digest identity

options is the mapping ({ key: 'laneKey', option: 'lane' }, { key: 'tickets', option: 'ticket', repeated: true }, { key: 'argv', positional: 0, repeated: true }). defaults holds only flags.<key>.default values; canonical Zod .default()s stay in CompiledCliOption.defaultValue for help text and are applied by inputSchema.parse, never before mapInput. The route manifest (RouteManifestCliCommand.projection, RouteManifestCliOption.aliases, RouteManifestCliProjection exported from agent-bundle/dev and the browser contracts) and the Workbench strict decoder mirror the fields and are tested; the old Workbench Routes page is not enriched (#600 is dismantling it) — projection details surface later in the selected-operation inspector of the Application explorer, and a comment in routes-page.tsx says so. #592 manifest v2 reserved routes.cli.commands[].projection; the name is kept. NormalizedBinEntry.generatedCli.projectionSources carries the sources to the bin build.

Runtime (build/entry-shell.ts, cli-entry.ts, build/cli-bins.ts, build/package-build.ts, test/cli.ts, test/render.ts). The generated bin (npm dist/bin/<name>.js and artifact bin/<name>.mjs, one template) imports each projection module beside its route module. The public shell's parseMcpCommandInput (cli-entry.ts) is the single confirmation guard for every command with mcp.confirm, bulk or projected: no --yes → CliUsageError (exit 2) before any callback runs, and yes is stripped. Then parseInput: (1) fills projection.defaults for absent keys — only those; (2) calls mapInput synchronously — a throw is a CliInputError (exit 2), a non-function a TypeError; (3) validates the mapped input with the canonical inputSchema (issues spelled --<option>), which is where canonical Zod defaults apply. Every command the CLI executable dispatches — src/cli route, explicit projection, and the bulk mcpCommands projection — runs the route with invocation: { kind: 'cli', operationId: 'tool:<server>/<tool>', surface: '<path>' } and providers { kind: 'cli', props: { args, command } }; the generated MCP server still passes kind: 'tool'. Both projection mechanisms are CLI surfaces, so a route never observes a different kind depending on which produced the command (owner requirement; previously the bulk path passed kind: 'tool'). The worker route table (route.kind) is untouched, so layouts still wrap. Help prints MCP tool: <server>:<tool> and Projection: <module> and lists aliases. The two duplicated bin sourceInputs lists are one cliBinSourceInputs helper that includes projection sources; the projection module is bundled into the bin only, never the Flight worker or MCP entry. The test harness (invokeCli/render) loads projection modules through the generated Rstest registry like routes, layouts, and providers (rstest/setup-module.ts emits projectionLoaders as static import()s, registry version 7; loadCliProjectionModule resolves lazily, file-URL import only without a registry, failures are AgentTestError) so .cli.tsx and .js-specifier value imports work under Rstest's module graph; it applies the identical steps and parity is pinned in entry-shell.test.ts.

Not forced, not leaked. No projection module → no command (bulk mcpCommands unchanged for the rest). ToolConfig, tools/list, annotations, _meta gain nothing.

Diagnostics (docs/diagnostics.md; the reference page renders from it)

Codes are AB4843–AB4845: #618 (event preflight gates, #595) landed first and holds AB4840/AB4841, so the projection codes moved up by three on the merge (1297c46dc); the design comment and earlier review threads say AB4840–AB4842 for the same three diagnostics.

Message shape CLI projection <module> for tool:<server>/<tool>: <detail>., sourcePath = the projection module. All errors: a projection that cannot compile has no correct partial output. AB4804 also names projection modules when routes.cli: 'conventional'; AB4814/AB4838/AB4839 gain the relabelled tool-route prefix.

Tests

• Unit tests/cli-projection.test.ts (27 cases): pairing without a route/contract binding; default command/aliases; renamed/repeated/positional/defaulted/relaxed options; confirmation + metadata defaults; AB4843 orphan/misplaced/parked; AB4844; AB4845; bulk exclusion + AB4822; AB4813; relabelled AB4814/AB4838; AB4837; digest stability across absolute roots (and change on a rename); custom-server skip; canonical yes on a confirming tool; positional name/aliases; AB4843 duplicate .cli.ts+.cli.tsx; one it per rejected mapInput form (ambient function/const, generator, async generator, async arrow/declaration, const-not-function, unfollowable re-export) plus an accepted-forms table. entry-shell.test.ts pins the bin template's projection import, parseInput order (defaults < mapInput < validation) and defaults: { laneKey: 'main' } only. Manifest (route-manifest-routes.test.ts) and Workbench decoder (route-manifest-client, routes-model) tests cover the mirrored fields; test-harness-manifest.test.ts pins submit as an explicit projection outside the bulk set.
• Projection pool: harness fixture gains src/mcp/harness/tools/submit.tsx + submit.cli.tsx (value-importing lib/submit-helpers.js — the shapes a native file-URL import cannot load under Rstest) (argv positional, laneKey → --lane, tags → --tag de-duplicated by mapInput, cwd relaxed and derived, confirm: false). tests/projection/cli-dispatch-projection.test.ts invokes the operation once per surface — invokeMcpTool('submit', …) and invokeCli(['submit', '--lane', …, '--', …]) — and asserts equal structured results, then tests each mapping separately (rename, repeated → array, -- passthrough, derived cwd, mapInput throw → exit 2, no --yes, help with short path/spellings/Projection: line, invocation.kind === 'cli' observed by a provider). cli-dispatch-projection.test.ts 'uses cli invocation kind for bulk and explicit CLI projections while MCP remains tool' invokes one route through the bulk projection, an explicit projection, and invokeMcpTool and asserts cli/cli/tool. cli-dispatch.test.ts 'requires confirmation for a projected mutation before dispatch and strips --yes from canonical input' tests the public shell with a spy callback.
• Integration cli-routes-build.test.ts: a temp project with src/mcp/demo/tools/submit.tsx + submit.cli.ts and a confirming purge.tsx + purge.cli.ts builds; the bin's submit --help shows the short path and renamed flags; argv round-trips through --json; cwd with a Zod .default('.') reaches mapInput as undefined (bin returns the derived root); purge without --yes exits 2 with the shared message, with --yes succeeds and no yes reaches the tool; inspect --routes shows projection. layout-build.test.ts now asserts a bulk-projected tool observes invocation: 'cli' from the bin while the layout's wrapped: route.kind stays tool and the MCP call reports tool. Full gate green after integration (1272862e5): build, typecheck, lint, lint:release, unit, route-unit, projection, integration (1131), docs site (parity + dead links).

Docs

docs/diagnostics.md, docs/entry-conventions.md; website en + zh: guide/authoring/package-entries.mdx (new "Project one tool as an idiomatic command"; bulk-projection exclusion), guide/authoring/mcp.mdx, guide/start/project-structure.mdx, guide/development/workbench.mdx, reference/configuration.mdx. Changeset agent-bundle: minor — reserving .cli.{ts,tsx} under src/mcp/** changes the meaning of a tool file that is legal today.

Consumer proof: cargo-hauler dry-run

Harness /tmp/596-dryrun/run.sh (never touches the checkout): pack agent-bundle/@agent-bundle/runtime/rsc-markdown-stream from this branch (339d65666), scratch-copy cargo-hauler, add src/mcp/hauler/tools/hauler_request.cli.ts + hauler_status.cli.ts (contents as in the design comment: status = renames only, request = argv positional + mapInput deriving cwd and splitting --after lists with cargo-hauler's parseTicketList), delete src/cli/request.tsx and src/cli/status.tsx, then inspect --routes --json, build, and the bin.

Every flag cargo-hauler pins in README.md, src/skills/**, and tests/route-unit/cli-dispatch.test.ts (--lane, --ticket, --status, --after … -- …) stays valid; its tests/schema-compat.test.ts (asserting the CLI copy equals the protocol enum) becomes moot. The pair's remaining CLI-vs-MCP difference — follow-up wording (hauler result vs hauler_result) — is a rendering choice the tool makes from agent().invocation.kind, now 'cli' under the projection.

Deferred

Short -x aliases (the shell rejects single-dash tokens), async mapInput (rejected today with AB4844; the shell's render is synchronous), deprecating ToolConfig.exitCode, projections for resources/prompts, a positional-specific description field (flags.<key>.description applies to a key that is positional), and the Workbench operation inspector's projection view (#600).

Deslop

Deslop: gpt-5.6-sol-medium, 52 edits (cba686084: 40 comments restating code in cli-projection.ts, cli-argv.ts, cli-commands.ts, fixtures and tests; 12 type/flow simplifications — discriminated unions instead of optional-field results + !, narrowed validateFlag fields instead of casts, one flags/relaxed loop, projectedCommands carrying its narrowed projection, mapInput output kept unknown, parseCliCommandInput taking the schema instead of module.inputSchema!). Plus the owner's own pass 92346d8dd (in-place mutation in parseCliCommandInput, resolvePolicy label once, no loader dedupe).

Self-review

Reviewer ≠ author model throughout (Grok never reviewed). Owner review 08:30 → all four correctness threads fixed and resolved inline, plus (A) invocation.kind normalized (not deferred) and (B) Workbench Routes page not enriched — see the reply comment.

Pass 1 on the pre-owner-review diff (339d65666): gpt-5.6-sol-medium (compiler half) + claude-fable-5-1-thinking-max (runtime half). Findings, all fixed: defaults conflation (→ CompiledCliProjection.defaults); harness projection loading (→ registry projectionLoaders); canonical yes on a confirming tool (→ AB4845); positional name/aliases (→ AB4845); AB4843 message shapes (→ one shape); dead GeneratedCliBinSurface casts; two --yes messages (→ confirmationRequiredMessage); mapInput TypeError wording. Re-run on 920441ca0: both APPROVE, no new findings.

Pass 2 on the owner-fix diff (1272862e5, after deslop): claude-fable-5-1-thinking-high (runtime/shell/harness) + gpt-5.6-sol-medium (compiler/IR/docs).

• Fable, Medium — parseMcpCommandInput stripped yes from every projected command, not only confirming ones, contradicting the compiler (yes reserved only when confirm) and dropping a non-confirming tool's canonical yes value. Fixed 8f035fe45: strip only when mcp.confirm; test 'hands a non-confirming projection its own canonical yes key untouched'.
• Fable, Low — three identical openRenderedSession branches in the bin template after the kind normalization. Fixed: one call.
• Sol, Medium — a bodyless overload signature (export function mapInput(a: A): B; with no implementation) was counted as a runtime binding. Fixed: scanRouteModuleExports adds a function declaration only when it has a body; test + AB4844 row.
• Sol, Low — docs say the Workbench "will surface" projection details in the operation inspector while the page does not show them. Dismissed: that is the forward note the owner asked for (Workbench redesign: make dev mode an application explorer with live route rendering, MCP/hooks traces, and embedded host sessions #600); future tense, no present-tense claim.
• Sol, Low — project-structure.mdx said bin/ appears only when src/cli/** exists. Fixed en/zh: any routed-CLI source (src/cli/**, bulk routes.mcpCommands, projection module).
• Sol, Low — no regression test for AB4804 with routes.cli: 'conventional' beside a projection module. Fixed: test added.
• Verified by both with no risk: single confirmation guard reachable only through runGeneratedCliEntry; kind: 'cli' in template and harness with MCP still tool and route.kind untouched; projection defaults only pre-mapInput; registry loader keys unique by construction (AB4843); deslop edits behavior-preserving; one changeset; every added file has a production importer.

Pass 3 (re-run after fixes) on 13bb3caa1: claude-fable-5-1-thinking-high — all three runtime fixes verified (non-confirming yes passthrough test uses the exact reproduced shape; one render branch; the body guard yields identical export sets for every valid TS shape, route-graph.test.ts 59/59), no concrete merge risks. gpt-5.6-sol-medium — compiler fixes and en/zh parity verified, forward-note wording confirmed future-tense, no concrete merge risks. Zero unresolved review threads. After pass 3: merged origin/main (#618, #624) with a code renumber only (AB4840–42 → AB4843–45, no logic change), plus the owner's 0901ae92d regression tests for the non-confirming yes passthrough; full gate green on 1297c46dc (build, typecheck, lint, lint:release, unit, route-unit, projection, integration 1132, docs site) and the owner's three test files re-run under the renumbered codes at b63d5b969. Then merged #620 (web surface; cliBinSourceInputs keeps projection sources and gains the config path main added; the non-web template hash pin in entry-shell.test.ts moves to this template's bytes) and #626; full gate green again on 3690b2aff (all pools, integration 1132, docs site); CI green on dc76050de (one packed-release.e2e flake — getByRole('heading', { name: 'Skills' }) also matches the Skills page's Source skills h2, unrelated to this PR — passed on re-run). Then merged #623 (import-only conflict in package-build.ts); full gate green on 96b1f159a.